<?php
	$title = "Documentation";
	include("header.html");
?>

<p class="centered">
    <i>
        This document is licensed under the
        <a href="http://www.gnu.org/copyleft/fdl.html">GNU Free Documentation
            License</a>. It is copyright 2003, jcoverage ltd.
    </i>
</p>

<h1>Introduction</h1>

<p>
    In a recent interview, James Gosling mused: "I don't think
    anybody tests enough of anything"
    (<a href="http://www.artima.com/intv/goslingD4.html"><i>A
    Conversation with James Gosling</i></a>).
</p>

<p>
    The fact is, software today is horrendously under-tested.
    Software maintainence costs are spiralling because few pieces of
    software can be changed with any degree of confidence that new
    bugs aren't being introduced.
</p>

<p>
    Without continual change and improvement, software is unable to
    continue meeting its users' needs. But without comprehensive
    automated test-suites, such change can also expose users to very
    undesirable risks: the risk that critical features no longer
    function as before, the risk of data loss and the risk of a
    system crash.
</p>

<p>
    Agile software development methodologies are helping improve the
    quality of software. Test-driven development, where tests are
    written to test features <em>before</em> those
    features are added, ensures that every piece of software is
    coupled with a test-suite.
</p>


<h2>Why use a coverage tool?</h2>

<p>
    No matter how good such methodologies are, and how diligently
    they're followed in an organisation, it isn't possible to
    ensure that software testing is as comprehensive as it could
    be. That's where tools can help.
</p>

<p>
    Cobertura is a free, simple and
    easy-to-use tool that will complement your existing Java
    development practices. It helps you discover exactly where
    your software is being tested and, more importantly, where it
    <em>isn't</em>. Cobertura will help you to view
    your software from a number of levels, from the entire system
    right down to an individual line of code.
</p>


<h2>Why use Cobertura?</h2>

<p>
    Sure, there are other coverage tools around, so what makes
    Cobertura different?
</p>

<p>
    Coverage analysers work by adding instrumentation. For Java,
    coverage analysers fall into three categories: those that
    insert instrumentation into the source code, those that add
    instrumentation to the Java byte-code, and those that run the
    code in a modified JVM. Cobertura adds instrumentation
    directly to the bytecode. We feel this is the best approach,
    since it does not require a modified VM, but still retains a big
    speed advantage over having to compile all your source code
    twice.
</p>

<p>
    Secondly, Cobertura is easy to integrate with Apache Ant. It
    comes with it's own Ant task definitions for you to use. You
    can choose to instrument any code you wish, from a single
    class to an entire system.
</p>

<p>
    Finally, Cobertura is completely free and not time-locked, so
    you can begin to use it today, without having to worry about
    what to do at the end of an evaluation period. What's more, we
    believe Cobertura is so easy to use, you'll be up and running
    in no time. So why not spend the next 15 minutes getting up
    and running with Cobertura. In that time, you'll certainly
    find out which parts of your code are completely tested, and
    where your code could do with a bit more testing.
</p>


<h1>Getting started</h1>

<p>
    This chapter assumes you are already familiar with the Ant build
    tool from Apache. If you're unfamiliar with Ant, you can find
    out about it at
    <a href="http://ant.apache.org/">http://ant.apache.org/</a>.
</p>


<h2>Adding the Cobertura custom tasks to Ant</h2>

<p>
    Cobertura seemlessly integrates with Ant using custom
    tasks. But before you can use these new tasks, you have to
    declare them in your Ant build file, typically named
    <code>build.xml</code>. This is done using the
    taskdef element, as shown below. Place this
    element anywhere in your Ant build file.
</p>

<pre><code>&lt;taskdef classpath="cobertura.jar" resource="tasks.properties"/&gt;</code></pre>

<p>
    Now we're ready to start using the Cobertura tasks.
</p>


<h2>Adding instrumentation to your classes</h2>

<p>
    Cobertura works by inserting
    instrumentation instructions directly into your compiled Java
    classes. When these instructions are encountered by the Java
    Virtual Machine, the inserted code increments various counters
    so that it is possible to tell which instructions have been
    encountered and which have not.
</p>

<p>
    You instruct Ant to create instrumented versions of your
    classes using the instrument task. The
    example below assumes your classes are in the directory
    <code>build/classes</code>.
</p>

<pre><code>&lt;cobertura-instrument todir="build/instrumented-classes"&gt;
    &lt;fileset dir="build/classes"&gt;
    &lt;include name="**/*.class"/&gt;
    &lt;/fileset&gt;
    &lt;/cobertura-instrument&gt;
</code></pre>


<h2>Running an instrumented application</h2>

<p>
    Once your classes have been instrumented by Cobertura, you can
    continue testing your application as you would normally via
    the JUnit task.
</p>

<p>
    Simply include a classpath
    entry for the instrumented classes <em>before</em>
    any reference to the original classes. This will ensure that
    the instrumented classes are loaded in preference to the
    original classes.
</p>

<pre><code>&lt;junit fork="yes"&gt;
    &lt;classpath location="${build.instrumented.dir}"/&gt;
    &lt;classpath location="${build.classes.dir}"/&gt;
    ...
    &lt;/junit&gt;
</code></pre>

<p>
    The instrumented classes found in
    <code>${build.instrumented.dir}</code> will be loaded
    before those found in
    <code>${build.classes.dir}</code> ensuring that the
    instrumented classes are used by JUnit.
</p>

<p>
    An instrumented class serializes information into the file
    <code>cobertura.ser</code>. Any existing
    information found in this file will be merged with the current
    information. In this way the instrumentation for several
    sessions of a running program can be merged together,
    producing a single coverage report. For example, the
    instrumentation from unit and functional tests can be merged
    together to produce a single coverage report.
</p>


<h2>Cobertura reporting</h2>

<p>
    An instrumented class serializes coverage information to the
    file <code>cobertura.ser</code>. Using the report tag,
    Cobertura can generate coverage reports
    in either <acronym>HTML</acronym> or <acronym>XML</acronym> format.
</p>

<h3><acronym>HTML</acronym> coverage report</h3>
<p>
    The default format for a Cobertura
    report is <acronym>HTML</acronym>.
</p>

<pre><code>&lt;target name="coverage"&gt;
    &lt;cobertura-report srcdir="${src.dir}" destdir="${build.coverage.dir}"/&gt;
    &lt;/target&gt;
</code></pre>

<h3><acronym>XML</acronym> coverage report</h3>
<p>
    The type of report generated is controlled by the format
    attribute of the report tag, which may be either
    <em>html</em> or <em>xml</em>. If the format
    is not supplied then it defaults to <em>html</em>.
</p>

<pre><code>&lt;target name="coverage"&gt;
    &lt;cobertura-report format="xml" srcdir="${src.dir}" destdir="${build.coverage.dir}"/&gt;
    &lt;/target&gt;
</code></pre>


<h2>Cobertura session merging</h2>

<p>
    Sometimes it is necessary to merge several Cobertura sessions
    together, for example, to produce a single consolidated
    coverage report from several different test runs of an
    application.
</p>

<h3>Session merging with the merge tag</h3>

<pre><code>&lt;cobertura-merge&gt;
    &lt;fileset dir="${basedir}"&gt;
    &lt;include name="**/cobertura.ser"/&gt;
    &lt;/fileset&gt;
    &lt;/cobertura-merge&gt;
</code></pre>

<p>
    The above fragment from an ANT build file, will merge
    together any serialised instrumentation that has been
    generated by Cobertura and produce a single consolidated
    instrumentation record.
</p>


<h2>Taking control with Cobertura and check</h2>
<p>
    All too often testing is something that is left until the end
    of the development cycle. For example, a coverage report is
    run on a weekly basis over the codebase, only when the
    coverage metrics fall below a certain pain threshold are the
    developers directed to increase their test coverage and
    quality.
</p>

<p>
    With Cobertura, development teams can
    choose to enforce <em>test driven development</em>
    on their codebase, by using the cobertura-check tag in their
    ANT build scripts.
</p>

<p>
    After each <em>instrumented</em> unit test
    sequence, Cobertura can do a <em>health check</em> to
    ensure that the codebase is being tested to the standard that
    has been demanded by the team. If coverage standards fall
    below the criterea set by the team, cobertura-check will fail the build.
</p>

<p>
    Our intention with cobertura-check
    is to ensure that test driven development practices are being
    followed by the entire development team. Inadequate testing
    will result in an immediate <em>automated</em>
    build failure, without having to study the entire coverage
    report.
</p>

<pre><code>&lt;cobertura-check branchrate="80" linerate="80"&gt;
    &lt;regex pattern="com.example.gui.*" branchrate="85" linerate="90"/&gt;
    &lt;regex pattern="com.example.tool.*" branchrate="55" linerate="80"/&gt;
    &lt;regex pattern="com.example.util.*" branchrate="85" linerate="95"/&gt;
    &lt;/cobertura-check&gt;
</code></pre>


<?php include("footer.html"); ?>
